dart_skills_lint reduce enforced cognitive complexity - #212

The goal of this pr was to make code easier to read an maintain. We dropped the cognitive complexity floor from 48 to 20.

Definition of done eval #212 (comment)

As a note: What a terrible agent pr description.

Model 3.5 pro preview
Relevant prompts

in #211 we moved to complexity checking to a new plugin. During that migration we found that complexity as defined by the new package was quite high. I want you to make the code in this repo easier to understand, maintain and drop the complexity score. Focus dropping the score to 20. Run your changes through adversarial review with a focus on maintainability and understandability. Any change that makes code harder to understand or harder to maintain but drops the complexity score should not say. Revert those changes and try again. If you cannot drop the score below 20 without making the code harder to understand or maintain tell me. If you find easy wins to reduce complexity across the repo but it does not reduce the worse cases then document them but do not implement them.

why do we need both entryLabelCap and entryLabelLower they seem almost identical
ok give me an example of the output so I can make sure it still provides a good user experience.
We went on a tangent because I noticed almost identical code and thought we should remove. Eventually after rejecting several suggestions and finding one that I liked from a code perspective. It turned out I did not like the user experience of the error messaging.

I reviewed the changes manually and ended up thinking that several of the methods that were added to reduce complexity needed dart docs.

add a dart doc for _findSeverityMismatches and _findFixableMismatches

Found the model had a preference for methods that have 2 return types that are kind of related. Like a text blob and if it needed to be modified. For each of the cases I asked it to try on just the at issue method.

I think _parseFrontmatter with the double return types is harder to read. Good idea but can you try a different organization?

Then I realize that the agent didnt enforce the new lower number.

hmm you seem to have dropped the as implemented floor but you didnt "tighten the bolts" to enforce that our new lower complexity will stay low.
I agree we need an automated assertion but could the skill instead point to the value in dart_skills_lint_workflow.yaml?

Some back and forth about the right place to put a new test. decided a new file made sense.

Agent pr description below

Summary

Refactors internal helper return types away from named record tuples (({ ... })) to standard single-value returns and reduces cognitive complexity across test suites to meet the threshold of 20.

Motivation and Context

Named record return tuples on private helper methods (_buildContext and _loadIgnores) added unnecessary syntactic overhead and tuple-unpacking noise at call sites. Additionally, nested helper closures inside main() in test suites (test/install_script_test.dart) caused cognitive complexity scores to accumulate on main() and exceed the repository's complexity limit. Moving those helpers to top-level private declarations correctly isolates their complexity scores.

Related Issues

Related to #211

What changed

• lib/src/validator.dart: Inlined frontmatter YAML parsing into _buildContext and refactored its return signature from Future<({SkillContext context, List<ValidationError>? fatalErrors})> to Future<SkillContext?>, passing fatalErrors as an out-parameter.
• lib/src/validation_session.dart: Extracted ignore path resolution into _resolveIgnorePath so that _loadIgnores returns Future<SkillsIgnores> directly instead of a record tuple. Added dartdoc clarifying "root" vs "entity" in _processRootSkillEntity. Removed a duplicate docstring block above processSkillRoot.
• lib/src/config_parser.dart: Audited and documented _parse* helper methods to clearly contrast global baselines vs path-specific overrides and single-item parsers vs collection iterators.
• test/install_script_test.dart: Extracted createMockRelease and runInstallScriptTest out of main() to top-level private helpers _createMockRelease and _runInstallScriptTest, dropping main()'s cognitive complexity score from 48 to 20. Added dartdoc for _createMockRelease.
• test/rules_md_consistency_test.dart: Added dartdocs for _findSeverityMismatches and _findFixableMismatches.
• .agents/skills/definition-of-done/SKILL.md: Updated cognitive complexity fail-threshold in the verification checklist to 20.

Testing Instructions

• Run dart format . to verify formatting.
• Run dart analyze --fatal-infos to verify static analysis.
• Run dart run cognitive_complexity --fail-threshold 20 lib test to confirm all declarations score <= 20.
• Run dart test to verify all 210 unit tests pass.
• Run dart run bin/cli.dart -d .agents/skills to validate all repository skills.